/**
 * Software License, Version 1.0
 * 
 * Copyright 2008 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgment:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgment may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or Granules, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called Granules, 
 * nor may Indiana University or Community Grids Lab or Granules appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 * GENERATED USING SOFTWARE.
 */
package cgl.granules.results;

import java.io.IOException;

/**
 * Some applications often need to include sequencing descriptors along with
 * their results. This interface snapshots some of the most commonly utilized
 * features by application developers.
 * 
 * @author Shrideep Pallickara
 * 
 */
public interface SequencingInfo {
	/**
	 * Checks to see if this contains information about a single sequence
	 * 
	 * @return <code>true</code>, if it contains single-sequence information;
	 *         <code>false</code> otherwise.
	 */
	public boolean hasSingleSequence();

	/**
	 * Retrieve the single-sequence information.
	 * 
	 * @return This method returns 0 if the value has not been set. Besides, the
	 *         boolean check to see if this has been set; the value could be
	 *         used by developers to determine if its a valid one.
	 */
	public long getSingleSequence();

	/**
	 * Check to see if the max sequence Info has been set. In most cases this
	 * would not be set. However, applications that require progress information
	 * this value would be useful in gauging the completion status. Typically,
	 * this value should be a constant.
	 * 
	 * @return <code>true</code>, if it contains the max sequence information;
	 *         <code>false</code> otherwise.
	 */
	public boolean hasMaxSequence();

	/**
	 * Retrieve the value of the max-sequence info.
	 * 
	 * @return The max sequence.
	 */
	public long getMaxSequence();

	/**
	 * Check to see if a sequence range has been specified.
	 * 
	 * @return <code>true</code>, if it contains a sequence range information;
	 *         <code>false</code> otherwise.
	 */
	public boolean hasSequenceRange();

	/**
	 * Retrieve the upper-bound of the specified range.
	 * 
	 * @return The upper bound of the range.
	 */
	public long getUpper();

	/**
	 * Retrieve the lower-bound of the specified range.
	 * 
	 * @return The lower-bound of the range.
	 */
	public long getLower();

	/**
	 * Sets the sequence range based on the specified upper and lower-bounds.
	 * 
	 * @param lower
	 *            The lower-bound of the sequence range.
	 * @param upper
	 *            The upper-bound of the sequence range.
	 * 
	 * @throws IllegalModificationException
	 *             If the SequencingInfo object has been closed for
	 *             modifications. Once a result is submitted to be written to
	 *             the output streams, the Results and its constituent objects
	 *             are closed for modifications.
	 */
	public void setSequenceRange(long lower, long upper);

	/**
	 * Sets the max-sequence information. This should be a constant for a given
	 * computation.
	 * 
	 * @param maxSequenceInfo
	 *            The max sequence information.
	 * 
	 * @throws IllegalModificationException
	 *             If the SequencingInfo object has been closed for
	 *             modifications. Once a result is submitted to be written to
	 *             the output streams, the Results and its constituent objects
	 *             are closed for modifications.
	 */
	public void setMaxSequence(long maxSequenceInfo);

	/**
	 * Set the single sequence Information.
	 * 
	 * @param singleSequence
	 *            The single sequence Information.
	 * 
	 * @throws IllegalModificationException
	 *             If the SequencingInfo object has been closed for
	 *             modifications. Once a result is submitted to be written to
	 *             the output streams, the Results and its constituent objects
	 *             are closed for modifications.
	 */
	public void setSingleSequence(long singleSequence);

	/**
	 * Check to see if the sequencing information is mutable. Once the
	 * sequencing information has been tagged as immutable, invoking the setter
	 * methods will result in a Runtime Exception.
	 * 
	 * @return <code>true</code>, if the sequence is mutable; <code>false</code>
	 *         otherwise.
	 */
	public boolean isMutable();

	/**
	 * Retrieve a byte[] representation of the object.
	 * 
	 * @return The byte[] representation of the SequencingInfo.
	 * @throws IOException
	 *             If there are problems in the marshalling process.
	 */
	public byte[] getBytes() throws IOException;

}
